createInvoiceReservation

HTTP method: POST

Use the createInvoiceReservation method to create an invoice payment if you have all of the information needed to process the payment without redirecting the customer to the invoice provider's site.

You can only use this method for invoice payments.
Test URL https://testgateway.altapaysecure.com/merchant/API/<method>
Production URL https://<YourShopName>.altapaysecure.com/merchant/API/<method>

To create invoice payments without manually collecting the social security or organisation number, use the createPaymentRequest method.

Parameter Description Type Mandatory Notes
terminal

The terminal determines the payment method and currency. For more information, see AltaPay's Payment Gateway.

This is the title of your terminal, found under Home > Terminal Settings in the Merchant Interface.

You can use variables in the terminal parameter. For example, if you want to call My EUR Terminal, you can set the terminal parameter value to 'My {currency} Terminal', where {currency} references the value of the currency parameter.

 string X  
shop_orderid

This is the internal ID of the order in your webshop.

In most integrations, you can use the same order ID for up to four orders. For PayPal and MobilePay payments, you can only use it for a singe successful transaction. The shop_orderid value is posted back to you, so you know the order to which the payment refers.

The shop_orderid value is posted back to you, so you know which order the payment refers to. 		[a-zA-Z0-9-]{1,100} X  
amount

This is the payment amount. If you are setting up a subscription, amount is the default amount for each capture.

You must use a dot as the decimal separator, and the amount can have maximum 2 decimals.

 float X  
currency This is the payment currency. It must be specified in an ISO-4217 format, either using the 3-digit numeric code, or the 3-letter character code. For more information about ISO-4217 currency codes, see https://en.wikipedia.org/wiki/ISO_4217.

[0-9]{3} or

[A-Z]{3}

X  
organisationNumber

The country specific organisation number for the customer, if it is a corporate customer.

 string   One of these parameters must be included.
personalIdentifyNumber

The country specific personal identity number for the customer, for countries where it is applicable. eg. Norway, Sweden, Finland

 string  
birthDate

The birthdate of the customer for countries where a personal identity number is not allowed to be used. Eg. Germany and Denmark.

 YYYY-MM-DD  
customer_info[gender] Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement. If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form). FMmalefemale    
transaction_info This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest. Array, max 50 entries.Each entry of max 255 chars.    
type

This is the authorization type. For more information, see Payment request types:

  • payment (default)
  • paymentAndCapture
  • verifyCard
  • credit
  • subscription
  • subscriptionAndCharge
  • subscriptionAndReserve
String    
accountNumber

For Avarto Germany an account number and bank code (BLZ) can be passed in, to pay via a secure ELV bank transfer.

 string    
bankCode

For Avarto Germany an account number and bank code (BLZ) can be passed in, to pay via a secure ELV bank transfer.

 string    
fraud_service

Setting the fraud_service parameter lets you select a different fraud detection service on the payment level.

none

maxmind

red

test

   
payment_source This identifies the source of the payment. The default value is eCommerce. eCommerce mobi moto mail_order telephone_order  

For Klarna KP: moto is treated as telephone_order.

Customer information

Parameter Description Type Mandatory
customer_info[username] The customer's e-user name or user id. This uniquely identifies the user in your system. string  
customer_info[type] Indicator of whether the customer is an individual or a business privatebusiness Private is assumed if not specified
customer_info[company_name] Name of the customer, if the customer type is Business string Yes, if the customer_info[type]=business
customer_info[company_type] The nature of the company

ltd - limited company

plc - public limited company

public_institution - public institution

Other - all other company types

 Yes, if the customer_info[type]=business
customer_info[vat_id] The company's VAT registration number string Yes, if the customer_info[type]=business
customer_info[shipping_att] The name of the person receiving the purchase on behalf of the company string Used if the customer_info[type]=business; optional but recommended
customer_info[shipping_lastname]

The last name for the customer's shipping address.

 String  
customer_info[shipping_firstname]

The first name for the customer's shipping address.

 String  
customer_info[shipping_address] The street address of the customer's shipping address.
See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
 string YesFor Norway, you can only ship to a customer's legal address
customer_info[shipping_postal]

The postal code of the customer's shipping address.

 string  
customer_info[shipping_region]

The region of the customer's shipping address.

 string  
customer_info[shipping_country]

The country of the customer's shipping address as a 2 character ISO-3166 country code.

 [a-zA-Z]{2}  
customer_info[shipping_city]

The city of the customer's shipping address.

 string  
customer_info[shipping_ref] A reference that can be used to track the order string Optional. Can be used for B2B transactions (the customer_info[type]=business)
customer_info[email]

The customer's email address.

string

Yes for all Przelewy24 transactions

Yes for NO and DE
customer_info[customer_phone]

The customer's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846).

 string  
customer_info[birthdate]

The birth date of the customer

Mandatory if your MCC code is 6012.

 Date (yyyy-mm-dd) Yes, if your MCC code is 6012
customer_info[billing_lastname]

The last name for the customer's billing address.

Mandatory if your MCC code is 6012.

 String

Yes, for DK, FI, and DE.
customer_info[billing_firstname]

The first name for the customer's billing address.

String

Yes, for DK, FI, and DE
customer_info[billing_address]

The street address of the customer's billing address.

See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
 string

Yes, for DK, FI, and DE
customer_info[billing_city]

The city of the customer's billing address.

Mandatory for fraud detection.

string  
customer_info[billing_region]

The region of the customer's billing address.

Mandatory for fraud detection.

string  
customer_info[billing_postal]

The postal code of the customer's billing address.

Mandatory if your MCC code is 6012.

Mandatory for fraud detection.

string

Yes
customer_info[billing_country]

The country of the customer's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here.

Mandatory for fraud detection.

[a-zA-Z]{2}

Yes
customer_info[billing_att] The name of the person/role who manages the billing for the company string  
customer_info[billing_ref] A reference, for example, cost center, that can be used to track the purchase order string Optional. Can be used for B2B transactions (the customer_info[type]=business)
customer_info[bank_phone]

The phone number of the bank where the credit card was issued.

 String  
customer_info[bank_name]

The name of the bank where the credit card was issued.

 string  
customer_info[gender]

Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement.

If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form).

FMmalefemale Required for Klarna payments in Germany (DE), Netherlands (NL), and Austria (AT) if customer_info[type]=private
customer_info[client_ip]

The customer's IP address.

Used for fraud detection.

 string
customer_info[client_session_id]

A unique identifier of the customers session (eg. an md5 hash of the real session id). Used for fraud detection.

 string  
customer_info[client_accept_language]

The language setting of the customers browser. Used for fraud detection.

 string  
customer_info[client_user_agent]

The customers browser identification. Used for fraud detection.

 string  
customer_info[client_forwarded_ip]

The customers IP address as forwarded by transparent proxy. Used for fraud detection.

 string  

Order lines

Parameter Description Type Mandatory
orderLines The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience. Array
Yes

For each order line:

Value

Description

Type

Mandatory

description

Description of an item.

String (255)

Yes

itemId

The item identification.

Each itemId must be unique within an order.

String (100)

Yes

quantity

The quantity of the item. The value must be greater than zero.

Decimal

Yes

unitPrice

The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount.

Decimal

Yes

taxPercent

This is the tax percentage of the unit price.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

No

taxAmount

This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence.

Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur.
The taxAmount is used for the calculation, and taxPercent is printed on the invoice.

Decimal

Yes

unitCode

The relevant measurement unit for the order line. For example, kg.

String (50)

 

discount

The order line's discount in percent.

Decimal

 
goodsType

The goods type of the order line - shipment| handling| item| digital| discount| gift_card| info| physical| sales_tax

  

imageUrl

The full URL of the icon for the item

String (255)

 
productUrl The full URL for the description of the item String (255)  

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Parameter Description
Result

The result of the request, for example:

  • Success
  • Fail
  • Open
  • PartialSuccess
  • Error. The MerchantErrorMessage and CardHolderErrorMessage elements show more information about the error.
Transactions Contains a set of Transaction elements, each describing the relevant transactions. For more information, see Transaction.

Request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/createInvoiceReservation \
  --header 'Authorization: Basic auth' \
  --data 'terminal=MyTerminal' \
  --data shop_orderid=abc123 \
  --data amount=2.25 \
  --data currency=EUR \
  --data language=da \
  --data transaction_info[Referer]='John Doe' \
  --data secondary_amount=5.89 \
  --data customer_info[billing_city]=Glostrup \
  --data customer_info[billing_region]=Copenhagen \
  --data customer_info[billing_postal]=2600 \
  --data customer_info[billing_country]=dk \
  --data customer_info[email]=myuser@mail.com \
  --data customer_info[username]=myuser \
  --data organisationNumber=1235323 \

XML response

<?xml version="1.0"?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-10-20T11:50:09+02:00</Date>
		<Path>API/createInvoiceReservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
		<Transactions>
			<Transaction>
				<TransactionId>416</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<CardStatus>NoCreditCard</CardStatus>
				<CreditCardToken />
				<CreditCardMaskedPan />
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<InvoiceOrderInfo />
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken/>
				<ShopOrderId>asdf23</ShopOrderId>
				<Shop>AltaPay Test Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>invoice_initialized</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>20</ReservedAmount>
				<CapturedAmount>0</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2011-10-20 11:50:09</CreatedDate>
				<UpdatedDate>2011-10-20 11:50:09</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
				<PaymentNature>Invoice</PaymentNature>
				<PaymentInfos />
				<CustomerInfo/>
				<ReconciliationIdentifiers />
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

If a payment was reserved, you can

If a payment was reserved and captured, you can: